Copyright: © 1996-97 InstallShield Software Corp.                  Help version 129


is InstallShield help is attempting to send you to the InstallShield Web site (www.installshield.com).


The ODBC Core Template

The ODBC Core Template provides a complete sample setup supporting ODBC 3.5.  The template installs a sample application, the core ODBC 3.5 files, and all registry entries required of an ODBC setup. It does not install any drivers or data source names.

The template comes complete with the redistributable files. They are located in subfolders of <InstallShield location>\TemplateData\ODBC Core Template Data. The folder names match the names of the file groups that use the files.

Using this template

You can easily customize the template to install ODBC with your application's setup. To test drive the sample setup, see Running the ODBC Core Template sample setup.

If the template is similar to your application's needs, you may be able to make simple changes to use it to create your own setup.  For more information, see Customizing the ODBC Core Template sample setup.

Or if you have an existing setup project that you want to add ODBC support to, see Adding ODBC support to an existing project.

Template requirements

The ODBC Core Template generates a 32-bit setup that runs on Windows 95 and Windows NT 4.0 or later. The template will not run on any other platforms.

The sample application requires an ODBC-compatible data source and driver to be installed on the target system. The template does not install DSNs or drivers, so it is your responsibility to set up a driver and DSN.

  See also

Feedback


Running the ODBC Core Template

Before you begin customizing the ODBC Core sample setup, you should run the template sample setup without any modifications. Follow the steps below to see the template sample setup run:

1.	Create a new project using the ODBC Core Template. Select New from the File menu of the InstallShield IDE. Select the Templates tab and then double-click the ODBC Core Template icon. A new project with the name ODBC Core Template is created. You can rename the new project, if desired, after closing it.

2.	Run the setup by selecting Run Setup from the Build menu.

3.	Verify that ODBC 3.5 was installed. Open Control Panel and double-click the 32bit ODBC icon.

4.	When the ODBC Data Source Administrator dialog opens, click the About tab and note the version numbers of the ODBC core components displayed there. They should all be in the 3.5 range.

Running the sample application

1.	Run the installed application by clicking the ODBC 35 Sample App icon in the Start\Programs menu. The sample application requires an ODBC-compatible data source to be installed on the target system.

2.	From the Login menu, choose Connect. The Connect to a Data Source dialog opens.

3.	In the Data Source field, select a data source from the drop-down list of existing data sources.

4.	In the User Name field, type "admin" (without the quotes).

5.	Leave the Password field blank, unless you know that the data source requires one.

6.	Click Connect to connect to the data source. The query window will open.

7.	In the SQL> field, enter a SQL statement valid for the data source you are accessing. For example, if your data source contains a table called Customers, you might enter SELECT * FROM CUSTOMERS.

8.	From the Query menu, select Execute SQL. The sample application executes the command and returns the rowset.

9.	Choose Exit from the Login menu to exit the application.

10.	If desired, you can uninstall the sample application by selecting ODBC 35 Sample App from the Add/Remove Programs applet in the Control Panel.

  See also

Feedback


Customizing the ODBC Core Template

Follow the steps below to customize the ODBC Core Template to install your application. (If you need to use an existing project, see Adding ODBC support to an existing project.)

Before you begin you may want to run the ODBC Core Template setup without modifications, as described in Running the ODBC Core Template sample setup, to verify that the template works correctly on your system.

1.	Customize the setup script as required by the needs of your setup. For example, you might want to change or remove the call to SdWelcome in the ShowDialogs user-defined function.

2.	Add the components, file groups, and setup types required to set up your application.

3.	Add the ODBC 35 component as a required component in your application's main component. Make sure you require ODBC 35 in a component that is guaranteed to be selected/installed during setup. At run time the template checks to see if the ODBC 35 component is selected, and if it is not, ODBC setup will not take place.

	Do not change the names of the ODBC 35 component, the ODBC Uninstall Files component, or the OLE DB Provider component.
4.	Replace the Setup.bmp splash screen graphic in the Splash Screen\Language Independent folder of the Setup Files pane with a splash screen of your own. If you do not wish to include a splash screen graphic, simply remove the provided Setup.bmp.

5.	Replace the License.txt file in the Language Independent\Operating System Independent folder of the Setup Files pane with your license agreement text.

6.	Compile, build, and test your project.

  See also

Feedback


Adding ODBC support to an existing project

Adding ODBC support to your project is a matter of reproducing the template's file links, file groups, components, and string table entries. Follow the steps below to add the ODBC support provided in the ODBC Core Template to an existing project.

	It will be easier to copy information from one project to another if you open the ODBC Core Template and your setup project in separate instances of the InstallShield IDE.
1.	Recreate the ODBC- and OLE DB-specific file groups in your project's File Groups pane.

a.	Duplicate the file groups' folder structure in your project's file groups pane. (You do not need to create a file group for the sample application. The ODBC- and OLE DB-specific file groups all begin with ODBC or OLE DB.) For more information, see Create a file group.

b.	Give each new file group the same properties that it has in the ODBC Core Template.

c.	Insert the same files into the file groups' Links folders.  For more information, see Organize my files into file groups.

2.	Recreate the ODBC- and OLE DB-specific components in your project's Components pane. (You do not need to create a component for the sample application. The ODBC- and OLE DB-specific components all begin with ODBC or OLE DB.) Give each new component the same properties that it has in the ODBC Core Template.

Remember that your application's main component or a component that is guaranteed to be selected/installed at run time must include the ODBC 35 Core component in its Required Components field.

3.	Copy the string table entries from the ODBC Core Template to the string table (or string tables if your setup is intended for distribution in more than one language) in your project. The ODBC-specific string table entries all begin with ISODBC_.

4.	Make sure that Odbcvc.h is included in the script before the program block and that Odbcvc.rul is included in the script after the endprogram keyword. Odbcvc.h and Odbcvc.rul are located in the IDE's Scripts pane, so you don't need to specify a path for these files.

5.	Call the ISODBCCheckRequirements function before transferring files with ComponentMoveData.

6.	Call the ISODBCInstallODBC function after calling ComponentMoveData. Before calling ISODBCInstallODBC, it is a good idea to check if the ODBC 35 Core component was installed, such as in the following lines from the ProcessAfterDataMove function in the template's script:

  nResult = ComponentIsItemSelected( MEDIA, ODBC_COMPONENT );

  if ( nResult = FALSE ) then

    return 0;

  endif;

  nResult = ISODBCInstallODBC ( MEDIA, TARGETDIR, @UNINST_KEY );

  if ( nResult != 0 ) then

    bInstallAborted = TRUE;

    return -1;

  endif;

7.	Ensure that Enable(SELFREGISTERBATCH) is called before ComponentMoveData and that Do(SELFREGISTRATIONPROCESS) is called after ComponentMoveData.  These calls register the self-registering files using the batch method.

8.	Run the Media Build Wizard to build your new setup with ODBC support.

9.	Test your setup.

  See also

Feedback


The ODBC Core Template components

The ODBC Core Template consists of the components listed below:

Component	Notes

Program Files	includes the sample application .exe file

ODBC 35 Core	contains the ODBC core self-registering and non-self-registering files to be installed into the Windows\System folder. This is the component that your application must require to support ODBC 3.5;  it, in turn, requires the ODBC Uninstall Files component and the OLE DB Provider component.

ODBC Uninstall Files 	contains an uninstallation log file stub and ODBC uninstaller DLL required to support uninstallation of ODBC

OLE DB Provider	contains the self-registering and non-self-registering OLE DB (ODBC) Provider files

  Feedback


The ISODBCCheckRequirements user-defined function

Syntax

ISODBCCheckRequirements ( szMedia );

Description

This function determines if the ODBC setup can proceed. It tests to see if any of the core ODBC files is locked (in use) on the target system, if the target system is Windows 95, Windows NT 4.0, or later, and if the user has administrator privileges on Windows NT.  If any of the tests fail, it sets a flag so ISODBCInstallODBC is skipped and deselects the ISODBC ODBC 30 component so that ODBC files are not copied to the target system.

Failures values are returned for handling outside this function. Call this function before transferring files with ComponentMoveData.

To call this function you must include Odbcvc.h before the program block and include Odbcvc.rul after the endprogram statement.

Parameters

szMedia

The name of the file media library that contained the ODBC components.

Return values

0

The function was successful.

< 0

The function was unsuccessful. The error codes listed below have the meanings indicated. Other error codes will have triggered messages indicating the problem that occurred.

-1

A core ODBC file is locked on the target system and the setup cannot proceed. Shut down any open programs and run the setup again.

ISODBC_ERRNO_OS

The target operating system must be Windows 95, Windows NT 4.0, or later.

ISODBC_ERRNO_NOTADMINISTRATOR

The setup cannot proceed because the user is not an administrator. Log on as an administrator and run the setup again.

Feedback


The ISODBCInstallODBC user-defined function

Syntax

ISODBCInstallODBC ( szMedia, szLogPath, szUninstKeyName );

Description

This function installs ODBC. It calls a function in _vc6ed.dll that handles calling the ODBC installer functions in the ODBC installer DLL. Call it after transferring files with ComponentMoveData.

To call this function you must include Odbcvc.h before the program block and include Odbcvc.rul after the endprogram statement.

Parameters

szMedia

The name of the file media library that contains the ODBC components that you transferred with ComponentMoveData.

szLogPath

The path to the ODBC uninstaller DLL _unodbc.dll and uninstallation log file _unodbc.log, usually TARGETDIR.

szUninstKeyName

The name of the registry key that will contain the uninstallation string.

Return values

TRUE

The function was successful.

FALSE

The function was unsuccessful. The error codes listed below have the meanings indicated. Other error codes will have triggered messages indicating the problem that occurred.

ISODBC_ERRNO_WRITETOLOGFILE

The function could not write to the ODBC uninstallation log file.

ISODBC_ERRNO_UPDATEUNINSTSTRING

Failed to update the uninstallation string for ODBC.

Feedback


Feedback
We welcome your suggestions for improving InstallShield help. To share your ideas, please visit http://www.installshield.com/talk/ or email doc@installshield.com.